---
title: Command Reference
description: Full reference for the Latitude CLI commands.
---

All commands support `-p, --path <path>` to run against a specific directory (default `.`), and `--dev` to use a local Gateway.

## init

Initialize a Latitude project in the current directory.

```bash
latitude init [-p <path>] [--dev]
```

- Prompts for your API key (or uses `latitude login`/`LATITUDE_API_KEY`)
- Detects npm project setup
- Lets you choose:
  - Create a new project (provide a name)
  - Use an existing project (enter `projectId`)
- Creates the prompts directory (asks before clearing a non-empty folder)
- Writes `latitude-lock.json`

`latitude-lock.json` example:

```json
{
  "projectId": 123,
  "rootFolder": "src/prompts",
  "version": "live",
  "npm": true
}
```

## status

Show project and version info plus a local vs remote diff summary.

```bash
latitude status [-p <path>] [--dev]
```

- Prints project link, version title/description
- Summarizes Added/Modified/Deleted prompts

## pull

Pull remote prompts to your local filesystem with a diff preview.

```bash
latitude pull [-p <path>] [-y] [--dev]
```

- Computes local vs remote changes
- Choose: Accept / Cancel / View details (opens pager for full diffs)
- `-y` skips confirmation and applies changes
- Saves prompts as `.js` files with a default export in npm projects
- Preserves `.promptl` files for non-npm projects
- Removes local files that no longer exist remotely

## push

Push local prompt changes to the current version.

```bash
latitude push [-p <path>] [-y] [--dev]
```

- Reads prompt files under `rootFolder`
- Shows a diff and asks for confirmation; `-y` skips confirmation
- Sends only changed files to the server
- Note: TypeScript prompt files (`.ts`) are not supported for reading content; use `.js` or `.promptl`

## checkout

Checkout a specific version or create a new version and switch to it.

```bash
latitude checkout [versionUuid] [-b <name>] [-p <path>] [--dev]
```

- `latitude checkout <versionUuid>`: updates `latitude-lock.json` and pulls that version
- `latitude checkout -b <name>`: creates a new version and switches to it
- Validates the target version before updating the lock file

## login

Store or override your API key in the system keychain.

```bash
latitude login [--api-key <key>] [-f]
```

- Warns if `LATITUDE_API_KEY` is set (that variable takes precedence)
- `-f/--force` to override without confirmation

## help

Show CLI help.

```bash
latitude help
```

## Prompt file formats

- npm projects:
  
```js
// src/prompts/welcome.js
export default 'Welcome to Latitude!'
```

Latitude always writes prompts for npm projects as `.js` modules with a default export to match modern ESM tooling.

- non-npm projects:

```text
# prompts/welcome.promptl
Welcome to Latitude!
```
